mIRC Syntax Tutorial

by Yochai Timmer

I've seen a lot of people who come into mIRC scripting help channels and don't even know the basic
syntax for any of the events they use.
I've organized mIRC's controls by topics, so it will be easier for you to find what you want.
Just click on a topic you want to read to open it or search for what you want in the page with Ctrl+f.

Aliases:

Aliases are mIRC's way to define functions.

There are 2 ways to create aliases, the first is to use the the aliases tab in the script editor, which will make all the aliases global (they can be used in all the script files), and you don't declare them as aliases, you just give a name and write the commands in { } brackets.

The second way is to declare the aliases in the remotes section, by using the alias declaration.

Alias [-l] alias_name {
    Arguments: $1-  = Contains all the text that was sent to the function.
                      $1,$2,$3  = Retrieves the specified token, divided by spaces.
                                         Unless the alias was called as an $identifier(Arg1,Arg2,Arg3)
                                         in which case they will return the arguments and may contain spaces.                                       
                      $prop  = Retrieves the the property that was used when calling that alias.
                      $isid  = Returns $true is the alias was called as an identifier (called with a $)
                      $show = Returns $true if the alias was called with a . (dot) meaning it should be quiet.
   The -l switch sets the alias as a local alias which can be called only from that script file.
   You can use Return <value> to return a value from an alias, or use
   Halt to stop the process that called the alias .
}

Examples:
 Alias echo_text {
     echo $1-
}
/echo_text hello world

Alias Power {
    var %val = $calc($1 ^ $2)
    if ($prop = neg) return $calc(-1 * %val)
    else return %val
}
//echo $power(2,4)
//echo $power(2,4).neg

Alias Identifier {
    if ($isid) return $1
    else echo $2
}
/echo $identifier(Hello world,Check this)
Returns: Hello world

/identifier Hello world
Returns: world

Note the difference with the way mIRC parses the spaces.
This is why when you use /commands you should use $qt(file name) for example, and in $identifiers
you don't have to use $qt.

The commands in the alias (and in fact in any part of the script) don't require the / character
before the command name. That character is the command prefix and it's saved for the editbox
to separate regular text from a command line. And it's not a fixed character, it can be set in mIRC's
options at: Options > Other > Command prefix .
So if you use the / for commands it might return an error if someone changed the prefix in his mIRC client.
If you have an alias with the same name as one of mirc's built in commands, you can still call mIRC's default command by using a ! before the command name.
Example:
alias server {
    echo -s Connecting: $1-
    !server $1-
}

/server irc.server.net
/*This will connect to the server using the alias, and will echo that line*/


/!server irc.server.net
/*This will call mIRC's default server command and connect to the server*/


A list of all the available $identifiers can be found in the mIRC help file: /help Identifiers
For a list of the commands, type /help and write / in the index.

 
If -Then -Else
mIRC scripting uses If-else lines just like any other programming language.The difference is that it has some built in operators that don't exist and some other scripting languages

if (v1 <operator> [v2]) { commands }
elseif (v1 <operator> [v2]) { commands }
else {
    mIRC reads the logical expressions from left to right, so the "first" expression must exist for mIRC to continue to the next.
    This is important when you want to save some CPU, you can put the "lighter" comparisons in the beginning and hope they'll fail
    so mIRC won't go on to the next comparisons.
    There are a number of signs you can put between the comparison expressions to combine them:
        &&    Means AND
        ||     Means OR
        ( )    Combines expressions as a group
        $&    Means expression continues in next line

    Parameters ( after the If line ):
        $v1 = Returns the last v1 used
        $v2 = Returns the last v2 used

    <operator> can be:
         = or ==    v1 is equal to v2 (It's considered good programming to use == and not just one =)
        ===   v1 is equal to v2 Case-Sensitive
        !=    v1 isn't equal to v2
        <    v1 is smaller/less than v2
        <=    v1 is smaller/less than or equal to v2
        >    v1 is more/greater than v2
        >=    v1 is more/greater than or equal to v2
        //    v2 is a multiple of v1
        \\    v2 is not a multiple of v1
        &    Bitwise comparison

    String operators:
        isin    String v1 exists in string v2
        isincs    String v1 exists in string v2 Case-Sensitive
        iswm    Wildcard string v1 matches string v2
        iswmcs    Wildcard string v1 matches string v2  Case-Sensitive
        isnum    v1 is a number in the range v2 which is in the form of n1-n2 (if you don't enter v2, it checks if v1 is a number)
        isletter    V1 is a letter in the range v2 which is in the list of letters v2 (if you don't enter v2, it checks if v1 is a letter)
        isalnum    Checks if v1 contains only letters and numbers (v2 is obsolete)
        isalpha    Checks if v1 contains only letters (v2 is obsolete)
        islower    Checks if v1 contains only lower case letters (v2 is obsolete)
        isupper    Checks if v1 contains only upper case letters (v2 is obsolete)

    Channel operators:
        ison    Nickname v1 is on the channel v2
        isop    Nickname v1 is an op on channel v2
        ishop    Nickname v1 is a half op on channel v2 (helper)
        isvoice    Nickname v1 is voiced on channel v2
        isreg    Nickname v1 is a regular nick on channel v2
        isban    Checks if v1 is banned from channel v2 (according to the internal ban list, /help $ibl)
        ischan    Checks if you are on channel v1 (v2 is obsolete)

    Auto-lists operators:
         isaop    Checks if v1 is a user in your auto-op list for channel v2 (v2 optional)       
         isavoice    Checks if v1 is a user in your auto-voice list for channel v2 (v2 optional)     
         isignore    Checks if v1 is a user in your ignore list with the ignore switch v2 (v2 optional)
         isprotect    Checks if v1 is a user in your protect list for channel v2 (v2 optional)
         isnotify    Checks if v1 is a user in your notify list

    Boolean Identifiers:
        Some of these identifiers have some other functions and props, but they can also be used like this:
        $isalias(name) = Returns $true if the alias name exists in your aliases or scripts.
        $isbit(A,N) = Returns $true if the Nth bit in the number A is turned on (1).
        $isdde(name) = Returns $true if the dde name exists.
        $isdir(Path) = Returns $true if the directory path exists.
        $isfile(Path\filename.ext) = Returns $true if the file name in the specified location.
        $istok(text,token,C) = Returns $true if the token (word) exists in the text with the character separator C.

    You can check if a variable or $identifier's value is not 0 or $null by just writing:
    if (%var) { }
    You can negate each one of these operators by putting a ! in front of them.
}

Examples:
if  ($1- isupper) {
    if (*hey*Yochai* iswm $1-) { msg $nick HEY ! }
    elseif (bye yochai iswm $1-) { msg $nick BYE ! }
    else { msg $nick Don't SHOUT ! }
}
/*checks if someone "shouts", and then divides it to 3 different situations (I assumed $nick works here, but it doesn't work in every event)*/

If (((#mirc ischan) && ($me == Yochai)) || (($me != Yochai) && (#mirc!ischan))) { }
/* Here I've made to comparison groups, and the OR means that one of them must exist */

If (!$isdir($mircdir\Check)) .mkdir $mircdir\Check /* an example for a boolean use of the conditions */

if (!%check) || (!%other) echo -a One of the variables doesn't exist.



Popups:

Popups are a list of predefined commands that appear when you right click on a window in mIRC.
Popups are also used to control window mouse events.


• There are 2 ways to create popups.
• One is in the popups tab in the script editor which is divided into sections already, so
• you don't have to declare what kind of manu it is, just create the menu items.
• And the second is by using the remotes and using the menu declaration.
• menu @window,channel,status,menubar,nicklist,query,* {
      Menu_name
      .Sub_menu : { commands }
      .-     /* creates a separation line */
      .Another : { commands }
     
      When you define a menu with submenus it should be declared without a command.
      The submenus will appear "in" the menu, and all the items will appear in the specified order.
  
• 
      Arguments:
          $submenu($identifier($1))  = Calls an identifier that creates a list of menus.
          &  = When placed before a letter, it will connect that letter with the specified menu item (and underlines the letter) use
                  only once per menu item.
          $1,$2  = Returns the specified token (divided by spaces) in the selected text in the window. Can be used in the nicklist
                        for example to return the nicknames.
          $active = Returns the window name.
  }
  
  Examples:
  menu channel {
      &Checking
      .Check : echo -a check
      .&Submenu
      ..Next: echo -a The next line will create a number of menu items
      ..$submenu(My_menus($1))
      ..$iif( $me == blah) : nick not_blah
  }
  Alias -l My_menus {
      if ($1 == begin) || ($1 == end)  return -  /*makes a separator in the beginning and end */ 
      while ($1 < 4) {
        return menu $1 : echo -a This menu number $1 /* $1 increases by 1 on each call */
      }
      return /* a return with no value ends the $submenu */
  }
  


Remote Events:

The remote events are mostly triggered by IRC events, although some of them are triggered by local mIRC events.
These events trigger automatically, and are very useful to automate your script.
I think it's important we start from the most basic events, and slowly move toward the more complicated ones.
In some events you can use ^ before the <level> and /haltdef to replace mIRC's default response.
$event will return the event type in any event triggered.

User Levels:

User levels in mIRC are assigned to users and events to limit a user's access to certain events.
This feature enables you to group users as friends or anything you want, and create events that will be limited to those groups.
The user level is set using the command: /auser [-a] <levels> <nick//address> [info]
The -a switch means that the user levels will be added to the existing levels, without mIRC will redefine the user's levels to the new ones.
The levels are local, and are stored in the Users section in the script editor ( can be accessed with $ulist() ).
For more examples check mIRC's help file.
Example:
/auser -a 5,10,Friend My_friend
/*This command adds the nick My_friend to access levels 5 10 and "Friend"*/

The significance of these levels are easily seen in mIRC's events.
All mIRC events have a <level> parameter in the event's syntax, except for the raw events that are server related..
So, lets divide the levels into 2 categories: Named levels and numeric levels.


Named levels:

Named levels are the easiest, you just enter a level name in the <level> parameter, and the event will trigger only if the user that triggered the event
has the same user level as specified in the event.
There's no need for comparisons, because there isn't a clear hierarchy of levels when you're looking at text level names.
You should avoid using the user level "me" because it's a saved word for user levels (will be explains later on).

Example:
on Friend:join:*: msg $chan Hey there $nick !
/*This event will run only if a user with a user level Friend joins the channel */

Numeric levels:

Numeric levels are much more dynamic, because numbers give you the ability to compare levels, and make events that are accessible to a range of levels.
By default mIRC allows access to events for all the users who have a higher or equal level to that specified in the event (for example on 2: means level 2 and higher).
If there are a number of similar events, with different user levels, mIRC will check for the closest level that matches the triggering user's level.
Here's a list of the available prefixes, comparisons and suffixes:


Prefixes:
   * = Allows any user to access the event.
   ^ = Triggers the event before mIRC's default respond, you can use /haltdef to stop mIRC's default respond.
   +level = Limits the event to the specified user level. 
   me:level: = Triggers the event only if you it was initiated by the local user.  
   !level = Triggers the event only if it wasn't initiated by the local user.
   @level = Triggers if you have ops in the channel that triggered the event.
   $level = Means that the <matchtext> parameter contains a regular expression.
   &level = Prevents the event from triggering if a /halt or /haltdef command was used in a previous event.


Examples:
on me:5:join:*: msg $chan Hey everybody !
/*This will only run when I join the channel, and I'm level 5 in the level list.*/

on @!100:deop:*: msg $nick Hey buddy, why did you deop $onick without asking me ?
/*Triggers only if you're oped in the channel, you didn't do the deoping, and the user who did is level 100 or above*/

on ^&+5:text:*:*: { echo $target $+(<,$nick,>) Level5 - $1- | haltdef }
/*If a previous script hasn't used /haltdef already, then it will trigger for a level 5 user only, before mIRC's default, and replace the default message text to: <Nick> Level5 - Text */

Comparisons:
Certain events have 2 users associated with the event, so you can use comparisons to check the level differences between the 2 users, we'll call the user who activated the event "the active user", and the target user we'll call "the passive user":
   <level = Checks if the active user's level is lower than the passive user's.
   <=level = Checks if the active user's level is lower or equal to the passive user's.
   >level = Checks if the active user's level is higher than the passive user's.
   =>level = Checks if the active user's level is higher or equal to the passive user's.
   =level = Checks if the active user's level is equal to the passive user's.
   <>level = Checks if the active user's level is Not equal to the passive user's (<> is used instead of != because ! is saved for the prefixes).

Examples:
on !<5:deop:*: msg $nick Hey, $onick is a closed friend than you are, watch out who you deop !
/*This event will run if a user with a level 5 or higher ( and not you ) deops a user with a higher user level*/

on =*:voice:*: msg $nick Hey, why'd you voice him ? he's the same level as you are !
/*This will trigger whenever someone voices another user with the same level as his*/

Suffixes:
Suffixes are used to prevent access to certain events, and they appear in the event's commands, not the <level> parameter.
There are only 2 suffixes:
   The = suffix prevents higher level user from accessing lower level events.
   The ! suffix prevents mIRC from processing any matching events of that type.

Examples:
on 1:text:*hi*:*: { do stuff }
on 5:text:*hi*:*: =
on 5:text:*hi*:*: {do more stuff }
/*This will prevent any user on level 5 from triggering the associated event from a lower level, but will allow another event for that level to be triggered*/

on 1:text:*hi*:*: { do stuff }
on 5:text:*hi*:*: !
on 5:text:*hi*:*: {do more stuff }
/*This will disable all events for the specified level that match that event. /*



mIRC events:

on <level>:APPACTIVE: {
    This event triggers when mIRC's active status has changed.
    Parameters:
       <level> = User level that will trigger the event.
    Arguments:
        $appactive = Returns $true if mIRC is currently the active application.
        $appstate = Returns the display state of the mIRC window: minimized, maximized, normal, hidden, or tray.
}

Example:
on *:appactive: if (!$appactive) showmirc -t

on <level>:START: {
    This event triggers when mIRC starts.
    Parameters:
       <level> = User level that will trigger the event.
    Arguments:
        $os = Operating system.
        $version = mIRC version.
}

Example:
on *:start: echo -s mIRC $version is loading on $os

on <level>:LOAD//UNLOAD: {
    This event triggers when the current script file is loaded or unloaded.
    Parameters:
       <level> = User level that will trigger the event.
    Arguments:
        $script = Returns the script file name.
}

Example:
on *:load: echo -s You've successfully loaded $script

on <level>:EXIT: {
    This event triggers when mIRC is being closed.
    Parameters:
       <level> = User level that will trigger the event.
}

Example:
on *:exit: unset %myvar

on <level>:DNS: {
    This event triggers when you get a dns result.
    This isn't a CTCP event, because mIRC finds the dns internally, but it's usually thought as one.
    Parameters:
        <level> = User level that will trigger the event.
    Arguments:
        $dns(N).prop = This identifier returns a number of values, depending on the prop:
            $dns(0) = Returns the number of addresses found.
            .addr = Returns the Nth address found.
            .ip = Returns the Nth IP found.
            .nick = Returns the nickname associated if /dns Nick was used.   
}

Example:
on 1:DNS:{
    echo -s I've found $dns(0) matching addresses:
    %a = 1
    while ($dns(%a))    {
        echo -s DNS: $dns(%a) Nick: $dns(%a).nick Address: $dns(%a).addr IP: $dns(%a).ip
        inc %a
    }
}



Raw events:

Raw <number>:<matchtext>: {
    This event catches numeric events from the server.
    These events include the results to the basic commands you send to the server like /join /whois /who.
    Parameters:
        <number> = The number of the event (defined in RFC 1459 - IRC protocol)
        <matchtext> = Checks if the matchtext appears in text returned from the server.
    Arguments:
        $numeric  = The number of the triggered event.
        $1-  = The text returned by the server. (Usually $1 is your nickname and $2 is the subject of the event).
}

Example:
Raw *:*: echo -a $numeric $1-



CTCP events:

ctcp <level>:<matchtext>:<*#?>: {
    This event catches basic client to client messages.
    These messages are used mainly to transfer information between clients, such as Ping, Version, DCC.
    Parameters:
        <level> = User level that will trigger the event.
        <matchtext> = Checks if matchtext appears in the text received.
        <*#?> = # means channel, ? means private, * means any.
    Arguments:
        $1-  = The text received in the event.
        $nick = The nickname that sent you the ctcp.
        $filename = If the ctcp is DCC related, then this returns the file name.
}

Examples:
ctcp *:DCC Send*:*: echo -a $nick is sending me $filename , and his IP is: $longip($gettok($1-,-3,32))
/* Check the DCC protocol in the help file to understand the last part */

ctcp ^*:ping:*: {
    ctcpreply $nick PING $ctime
    haltdef
}

on <level>:CTCPREPLY:<matchtext>: {
    This event checks for mIRC ctcp replies, or text sent with the /ctcpreply command.
    Parameters:
        <level> = User level that will trigger the event.
        <matchtext> = Checks if matchtext appears in the text received.
    Arguments:
        $1- = The text received in the event.
        $nick = The nickname that sent you the ctcpreply.
}

Example:
on *:ctcpreply:ping *: {
    echo -s $+($nick's) ping is $calc($ctime - $2)
    haltdef
}



DCC events:

on <level>:FILESENT//SENDFAIL//FILERCVD//GETFAIL:<matchtext>: {
    These events trigger when a file send/get fails or finishes.
    Parameters:
        <level> = User level that will trigger the event.
        <matchtext> = Checks if the file name matches matchtext.   
    Arguments:
        $nick = The nickname you are getting from/sending to
        $filename = The name of the file associated with the event.
        $get(-1)/$send(-1) = The identifiers that contain the send/get status.
}

Examples:
on *:getfail:*: {
    if ($calc($get(-1).rcvd - $get(-1).resume) == 0) echo -s You were unable to connect to $nick .
}
on *:filesent:*.txt,*.doc: {
    echo -s You've just sent the document $nopath($filename) to $nick
}

on <level>:DCCSERVER::<Chat//Send//Fserve>: {
    This event triggers when someone is trying to DCC you via your DCC Server.
    People who are firewalled and cannot send via normal DCC usually request that you open a DCC Server
    so they can connect passively.
    Parameters:
        <level> = User level that will trigger the event.
        <Chat//Send//Fserve> = Triggers for either Chat, Send or File Server.
    Arguments:
        $nick = The nickname that's trying to connect to your DCC server.  
        $address = The address of the user that's trying to connect.
        $filename = The file that's being sent through the DCC server.
}

Example:
on *:DCCSERVER:Send: if (.exe isin $filename) { echo -s $nick is sending you an .exe file ! | /halt }



Server events:

on <level>:LOGON:<matchtext>: {
    This events triggers when mIRC tried to logon to a server.
    This can either trigger before mIRC sends the logon commands (PASS,NICK,USER) or after.
    Parameters:
        <level> = User level that will trigger the event.
        <matchtext> = Checks if matchtext appears in the Network name.
    Arguments:
        $network = Returns the network name.
        $server = Returns the server name.
        $port = Returns the connected port.
}

Example:
on ^*:LOGON:*:echo Logging on to $network on $server port: $port
/* The ^ means it will trigger Before mIRC logs in to the server. */

on <level>:CONNECT/CONNECTFAIL//DISCONNECT: {
    This event triggers when you either connect to a server (right after the MOTD) or disconnect, or you were unable to connect
    to the server (after all the retries).
    Parameters:
        <level> = User level that will trigger the event.
    Arguments:
        $server = Returns the server name.
        $network = Returns the network name (if connected).       
}

Example:
on *:connect: if ($network == My_network) msg nickserv identify password

on <level>:ERROR:<matchtext>: {
    This event triggers when you receive an error message from the server (usually on disconnect).
    Parameters:
        <level> = User level that will trigger the event.
        <matchtext> = Checks if matchtext appears in the error message.
    Arguments:
        $1- = The error message sent by the server.
}

Example:
on *:error:*server*full*: echo -s The server is full :(

on <level>:NOTIFY//UNOTIFY: {
    This event triggers when the server detects that a user that's on your notify list has joined the network.
    Parameters:
        <level> = User level that will trigger the event.
    Arguments:
        $nick = The nickname that has joined the network.   
}

Example:
on *:notify: msg $nick Hey, how are you ?

on <level>:SNOTICE:<matchtext>: {
    This event triggers when you receive a notice from the server.
    Parameters:
        <level> = User level that will trigger the event.
        <matchtext> = Checks if the notice matches matchtext.
    Arguments:
        $1- = Contains the server's notice.
}

Example:
on *:snotice:*: echo -s $server has sent you a notice: $1-

on <level>:PING//PONG: {
    This event triggers when the server pings you.
    Parameters:
        <level> = User level that will trigger the event.
    Arguments:
        $1- = Contains the server's ping message.    
}

Example:
on *:PONG:echo -s pong reply: $1-

on <level>:WALLOPS:<matchtext>: {
    Triggers when you get a wallops message from the server.
    These messages are sent to all the opers and +w users on the network.
    Parameters:
        <level> = User level that will trigger the event.
        <matchtext> = Checks if the message matches matchtext.
    Arguments:
        $1- = Contains the server's message.
        $nick = The nick who sent the message.
        $network = Gives you the triggered network.
}

Example:
 on *:WALLOPS:*warning*:/echo $nick issued warning at $time



Channel events:

These events are usually related to channel management.

on <level>:JOIN//PART:<#,[#]>: {
    These events trigger when someone joins or parts a channel.
    Parameters:
        <level> = User level that will trigger the event.
        <#> = The matching channel name, (if you just type # it means any).
    Arguments:
        $me = Your nickname.
        $nick = The joining/parting nickname.
        $chan = The channel which the user has joined to or parted from.
        $1- = Holds the parting message.
}

Example:
on me:join:#: describe $chan says hi

on <level>:QUIT: {
    This event triggers when someone quits the server (not you).
    This is not a channel related event, but usually is considered so for channel management.
    Parameters:
        <level> = User level that will trigger the event.
    Arguments:
        $1- = Holds the quitting message.
        $nick = The quitting nickname.
        $network = The network you're on.
        $comchan = Usually used instead of $chan (which doesn't exist here) to fined the common channels
                            you have with the nickname that quitted.
}

Example:
on *:quit: {
    var %a = 1
    while ($comchan($nick,%a)) {
        msg $v1 Bye $nick !
        inc %a
    }
}

on <level>:MODE//SERVERMODE:<#,[#]>: {
    This events triggers when a user (or server) changes a channel's modes.
    Parameters:
        <level> = User level that will trigger the event.
        <#> = Channel or channel names to be matched (if you just type # it means any)
    Arguments:
        $1- = The channel modes that were changed.
        $chan = The channel where the event happened.
        $chan($chan).prop = This identifier contains the channel properties, check the available props in the help file.
        $nick = The nickname that changed the modes (if it's not a servermode event).
        $mode(N).prop = Returns the Nth affected nick in the mode change, check the available props in the help file.
}

Example:
on @*:MODE:#:echo -s $nick changed $chan mode to $1- /* The @ means that it will trigger only if you're oped */

on <level>:OP//DEOP:<#,[#]>:
on <level>:SERVEROP:<#,[#]>: { Triggers when someone was oped by the server. Doesn't have the $nick argument }
on <level>:HELP//DEHELP:<#,[#]>:
on <level>:VOICE//DEVOICE:<#,[#]>: {
    These events trigger when a user's mode was changed in a channel.
    Parameters:
        <level> = User level that will trigger the event.
        <#> = Channel or channel names to be matched (if you just type # it means any).
    Arguments:
        $nick = The channel operator that gave the command.
        $chan = The channel where the event happened.
        $opnick = The nickname that was oped.
        $vnick = The nickname that was voiced.
        $hnick = The nickname that was helped.
}

Example:
on @*:devoice:*: if ($vnick == my_friend) mode $chan +v $vnick 

on <level>:BAN//UNBAN:<#[,#]>: {
    These events trigger when someone was either banned or unbanned from a channel.
     Parameters:
        <level> = User level that will trigger the event.
        <#> = Channel or channel names to be matched (if you just type # it means any).
    Arguments:
        $nick = The nickname that did the banning.
        $chan = The channel nickname was banned from.
        $banmask = The mask (address) that was banned. 
        $bnick = The nickname that was banned. (only filled if $banmask includes a nickname).
}

Example:
on *:ban:*: echo $chan $nick just banned $iif($bnick,$bnick,$banmask) !

on <level>:TOPIC:<#[,#]>: {
    This event triggers when the channel's topic has changed.
    Parameters:
        <level> = User level that will trigger the event.
        <#> = Channel or channel names to be matched (if you just type # it means any).
    Arguments:
        $1- = The new channel's topic
        $nick = The nickname who changed the topic.
        $chan = The channel where the event happened.
}

Example:
on *:topic:*: echo $chan $nick has changed the $+($chan,'s) topic to: $1-

on <level>:KICK:<#[,#]>: {
    This event is triggered when someone's been kicked out of a channel.
    Parameters:
        <level> = User level that will trigger the event.
        <#> = Channel or channel names to be matched (if you just type # it means any).
    Arguments:
        $nick = The nick that kicked nickname out.
        $chan = The channel that the event triggered in.
        $knick = The nick that was kicked from the channel.
        $1- = The kick message.
}

Example:
on *:kick:*: echo $chan $nick has kicked $knick because: $1-

on <level>:INVITE:<#[,#]>: {
    This event is triggered when someone tries to invite you to a channel.
    Parameters:
        <level> = User level that will trigger the event.
        <#> = Channel or channel names to be matched (if you just type # it means any).
    Arguments:
        $nick = The nickname that's inviting you.
        $chan = The channel you are invited to.
}

Example:
on *:invite:*:  msg $nick I don't wanna join $chan !



Window events:

Custom windows may have popups, check the popups section.

Menu @window_name {

•     Window mouse events are triggered like popups, using the menu function.
  
      Mouse Events:
         dclick  = Activates when you double click in the window.
          rclick = Activates when you right click in a window.
  
•         lbclick = Activates when something is selected inside a window.
•         sclick = Activates when you click once in a window. (Picture window event)
•         uclick = Activates when the left mouse button was released in the window. (Picture window event)
  
•         drop = Activates when something is dropped inside a window. (Picture window event)
•         mouse = Activates when the mouse is moved over or in the window. (Picture window event)
          leave = Activates when the mouse leaves the window. (Picture window event)
• 
      Arguments:
          $1 = This returns the selected line number, if a line was selected.
  
•         $mouse = This identifier holds all the mouse properties (for example: mouse position when the event triggered).
          $leftwin = Returns the window name that the mouse just left (used in the leave event).
          $leftwinid = Returns the window ID that the mouse just left (used in the leave event).
  
• 
  
• }
  
  Example:
  menu @testwin {
      dclick: echo Double click at: $mouse.x , $mouse.y in $active
      lbclick: echo You've selected $1 in $active
     
  }
  
  on <level>:ACTIVE:<*#?=!@>: {
      This event triggers when a window becomes the active window.
      Parameters:
           <level> = User level that will trigger the event.
          <*#?=!@> = @ means custom window , ! means file server, = means DCC chat, ? means private,
                                # means channel , * means any.
      Arguments:
          $active = Returns the newly active window name.
          $lactive = Returns the last active window name.   
  }
  
  Example:
  on *:active:*: echo -a You've changed windows from $lactive to $active
  
  on <level>:OPEN//CLOSE:<?|@|=|!|*>:<matchtext>: {
      These events trigger when you either open a new window, or close an existing one.
      Parameters:
          <level> = User level that will trigger the event.
          <*?=!@> = @ means custom window , ! means file server, = means DCC chat, ? means private,
                               * means any.
          <matchtext> = Checks if the window's name matches matchtext.
      Arguments:
          $target = The window's name.     
  }
  
  Example:
  on *:close:*:*: echo -s You've just closed $target !
  
  
on <level>:KEYDOWN//KEYUP:<@>:<keyN,>: {
    This event triggers when you press any key in a custom window.
     Parameters:
        <level> = User level that will trigger the event.
        <@> = The name of the window that should trigger the event (if you just type @ it means any window).
        <keyN> = Checks if the key's ASCII value matches keyN.   
    Arguments:
        $keyval = Returns the ASCII value of the pressed key.
        $keychar = Returns the key's character.
        $keyrpt = Returns $true if the key is repeating due to a user holding down the key
        $target = Returns the target window's name.
}

Example:
on 1:KEYDOWN:@:37,38,39,40:echo pressed cursor key $keyval $keyrpt in $active
• 
  

Input events:

The input events let you control the text input (the text you type) in the window.

on <level>:INPUT:<*#?=!@>: {
    This event triggers when you press enter in the editbox.
    Parameters:
        <level> = User level that will trigger the event.
        <*#?=!@> = @ means custom window , ! means file server, = means DCC chat, ? means private,
                              # means channel , * means any.
    Arguments:
        $1- = The text entered in the editbox.
        $ctrlenter = Returns $true if Cntrl+Enter was pressed.
        $target = Returns the target window name, which is the window the text was entered in.
}

Example:
on ^*:input:#: {
    echo -a $+({,$me,}) : $1-
    haltdef
}

on <level>:TABCOMP:<*#?=!@>: {
    This event will trigger when you press the TAB key in an editbox.
    This is usually used to change the tab's nick completion function.
    Parameters:
         <level> = User level that will trigger the event.
        <*#?=!@> = @ means custom window , ! means file server, = means DCC chat, ? means private,
                              # means channel , * means any.
    Arguments:
        $1- = The text entered in the editbox.
        $target = Returns the target window name.
}

Example:
on ^*:tabcomp:*: haltdef  /*Stops the nick completion*/ 



Text events:

on <level>:TEXT//NOTICE//ACTION:<matchtext>:<*#?>: {
    These events trigger when any text, notice or action (/me) is sent to a window.
    Parameters:
        <level> = User level that will trigger the event.
        <matchtext> = Checks if the file name matches matchtext.
        <*#?> = ? means query window, # means a channel window , # means any window .
    Arguments:
        $1- = Contains the text message.
        $nick = The nickname that's sending the text.
        $chan = The channel the text was sent to (if it's in a channel).
        $target = The window that called the event.
}

Example:
on *:action:*slap*:*: msg $nick Damn that's lame

on *:CHAT/SERV:<matchtext>: {
    These events trigger when any text is sent to a DCC Chat window or File Server.
    Parameters:
        <level> = User level that will trigger the event.
        <matchtext> = Checks if the file name matches matchtext.
    Arguments:  
        $1- = Contains the text message.
        $nick = The nickname that sent the text.
        =$nick = The DCC window which called the event 
        $cd = The current directory in the File Server.
}

Example:
on *:CHAT:*hi*: msg =$nick Hi there $nick !

on <level>:HOTLINK:<matchtext>:<*#?=!@>: {
    This event triggers twice. First you need to set a hotlink with a ^ to link the text to the event.
    Then use a regular hotlink event to activate the text when it's clicked on.
    Parameters:
        <level> = User level that will trigger the event.
        <*?=!@> = @ means custom window , ! means file server, = means DCC chat, ? means private,
                             * means any.
        <matchtext> = Checks if the window's name matches matchtext.
    Arguments:
        $1 = The word in the text that was clicked.
        $target = The window that called the event.
        $hotline = The entire line that is hotlinked.
        $hotlinepos = The the word's place in the text, and the line number.
    In the first hotlink (with the ^):
        $mouse.key  = Checks if you right clicked or left clicked on the link.
        Return = Hotlinks the word.
        Halt = The word isn't linked.
}

Examples:
on ^*:hotlink:*:*: {
    if ($1 == hi) return
    else halt
} /*This will link only the word hi in the text*/

on *:hotlink:*hi*:*: {
    if ($1 == hi) && ($gettok($hotlinepos,1,32) == 2) msg $target Hi there $remove($gettok($hotline,1,32),<,>) !
}
/* If the word "hi" is the first word in the text (number 2 because of the nickname that appears in the line) then it will work */



Sound events:

on <level>:MIDIEND//MP3END//WAVEEND: {
        This event triggers when a sound file that was called by mIRC finishes.
    Parameters:
        <level> = User level that will trigger the event.
    Arguments:
        $filename = The file that finished playing.
        $sound($filename) = Can give information about the file if it's an MP3 file.
}

Example:
on *:mp3end: {
    echo -a Just finished playing $nopath($filename) .. $sound($filename).title by $sound($filename).artist
}

on <level>:AGENT: {
    This event triggers when an agent has finished speaking.
     Parameters:
        <level> = User level that will trigger the event.
    Arguments:
        $agentname = Returns the name of the agent associated with the event.  
}

Example:
on *:agent:/echo Agent $agentname has finished speaking

on <level>:VCMD:<matchtext>:<*#?@>: {
    This event triggers when mIRC recognizes a voice command, via an external Speech Recognition software.
    Voice commands are added by the command /vcadd , and they are linked to a command by this event.
     Parameters:
        <level> = User level that will trigger the event.
        <matchtext> = Checks if the command matches matchtext.
        <*#?@> = @ for custom window, ? for query, # for channel, * for any.
    Arguments:
        $1- = Contains the command line recognized by the Speech Recognition software.
        $active = The active window when the event triggers.
}

Examples:
Alias Set_commands {
    if ($vcmdver == $null) halt
    vcmd -c on
    vcadd connect Dalnet, connect Efnet, connect Undernet
    vcadd Part channel
}

on *:vcmd:connect*:*: server -m $2
on *:vcmd:part channel:#: part $active



Custom events:

Custom events in mIRC are called signals.
To trigger a signal event you'll have to use the command /signal from within the script.
/signal [-n]  <name> [arguments]
The <name> will be the signal name, and -n will activate the signal immediately (instead of after the script ends).
That command will trigger all the signal events in all the script files.
The idea, is that you don't have to call specific aliases, you can just call an event from anywhere in your script
and attach the event to the aliases you want to call.
Usually used for modular scripting, and there are some DLL's that send signals to mIRC because they don't
have an actual event.

on <level>:SIGNAL:<matchname>: {
     Parameters:
        <level> = User level that will trigger the event.
        <matchname> = Checks if the signal name matches matchname.
    Arguments:
        $1- = The arguments that were sent with the signal.
        $signal = The signal name.
}

Examples:
on *:text:*:*: if (Badword isin $1-) signal -n Badword $nick $target $1-
on *:notice:*:*: if (Badword isin $1-) signal -n Badword $nick $target $1-

on *:signal:Badword: {
    msg $1 You've said Badword in $2 ! $+(",$3-,")
}



Socket events:

Socket events are your way to connect to the internet via mIRC scripts.
You won't be able to use them by just reading this tutorial, because I can't explain every
internet related protocol out there.
So, I'll just show you how the events work, and you must read the protocol for whatever you want to connect to.
First of all, any socket connection should be opened with the /sockopen or /socklisten commands.
/socklisten [-d] [bindip] <name> [port]
This command will make mIRC listen for the port (Passive).
/sockopen [-de] [bindip] <name> <address> <port>
This command will send a connection to the required address and port.
Bindip is used when you have more then one IP on your PC (like 2 net cards), so you can select the IP you want to use.
Note that the port isn't random, you'll have to read the protocol you're using to get the right port.
For example, HTTP (regular internet connection) uses port 80, and IRC servers use a range of ports: 6667,7000 and 9999,6697 for SSL.

on <level>:SOCKOPEN//SOCKLISTEN//SOCKWRITE//SOCKREAD//SOCKCLOSE:<matchname>: {
     Parameters:
        <level> = User level that will trigger the event.
        <matchname> = Checks if the socket name matches matchname.
    Arguments:
        $sockname = The socket name that triggered the event.
        $sock($sockname) = Holds most of the information about the socket connection.
        $sockerr = If the value is larger than 0, then there's an error.
        $sockbr = Checks if the information was read from the buffer
        $portfree(N) = Checks if port number N is free.
}

Example:
Alias Get_addr {
    sockopen Get_addr whois.cyberabuse.org 43
    set %Get_address $1-
}

on *:sockopen:Get_addr: {
    if ($sockerr) echo -s Unable to connect to whois server.
    else sockwrite -nt Get_addr %Get_address
}
The sockopen triggers when the socket connects.
You usually need to send some initializing commands when you connect (with /sockwrite)

on *:sockread:Get_addr: {
    sockread %data
    if (%data) {
        if (%data == % http://www.cyberabuse.org/whois/) { unset %Get_address  | sockclose $sockname }
        if (% $+ * !iswm %data) echo 2 -s %data
    }
}
The %data variable contains the data retrieved from the address.
If you connect to an HTTP site, you'll probably get HTML text.


 
Dialogs:

Dialogs are an important feature for mIRC scripts interface.
Most scripts use DLL's to enhance the dialog's interface, but I won't go into that, and I'll just show you how to use
mIRC dialogs.


Dialog Prefix:

First of all you need to create a dialog Table, which is the dialog's design.

Dialog [-l] <name> {
   Parameters:
        [-l]  = Will make the table available only in the current script file.
        <name> = Defines the dialog table's name.
   Inside the dialog table you will set all the dialogs design by placing dialog items.
   You can find the full list of these items in: /help DIALOG prefix
   First of all you'll need to set up the dialog:

   Size <x y w h> = X and Y are the position of the dialog on your screen.
                              W and H are the dialog's width and height.
   Option < dbu//pixels//notheme> = Select the dialog's dimension type. dbu means dialog base units, which basically
                                                       means that the dialog will look the same on any resolution. pixels will set the dialog's
                                                       size in pixels.
    Icon filename, index  = Sets the dialog's Icon. Index is the icon's number in the file. If you are using .ico files or files with no
                                       other icons in them, just use 0 for the index.
    Title "text" = This sets the dialog's title.

    Next, you'll want to add the items, there are a lot of item types you can add (check the help file), but this is the basic syntax:

    <item type> ["text",] <Id>, <x y w h>, <style> [%variable] <,Tab N>
    Parameters:
        <item type> = The item type you want to create, /help DIALOG prefix         
        ["text"] = Some items can be initiated with text in them
       <Id> = This is the Id number that will be associated with the item. This is what will be used later in the events and $identifiers 
       <x y w h> = X and Y are the position of the item in your dialog. W and H are the item's width and height.
       <style> = Each item type has a number of styles which you can choose from.
       <%variable> = If you put a %variable name, it will be set with the contents of the item when the dialog closes. 
       <Tab N> = The item can be associated to a certain tab, or menu (if it's a menu item).

    There are 3 important styles you need to remember, which you can only have 1 of each in any dialog:
    Ok = This is set to be the "ok" button, this item will close the dialog when pressed.
    Cancel = This is set to be the chancel button, this item will close the dialog when pressed.
    Result = This identifies the item with the return value that will be returned when using $dialog.
}

Now, there are 2 ways of creating a dialog:
/dialog -m[Other parameters] <name> <table> [x y w h] [text]
Parameters:
    -m = creates a modeless dialog (meaning it won't return a result), and after that you can add other parameters.
    <name> = The name that will be associated with the dialog (can't have 2 dialogs with the same name)
    <table> = The dialog table you want to use for that dialog.
    [x y w h] = X and Y are the position of the dialog on your screen. W and H are the dialog's width and height.
    [text] = Will set the dialog's title.

$dialog(name,table[,parent])
This will call the dialog and return the result associated with the Result item.
Parameters:
    name = The name that will be associated with the dialog (can't have 2 dialogs with the same name)
    table = The dialog table you want to use for that dialog.
   [parent] = The dialog's parent window, this can be any window name or: -1 = Desktop window, -2 = Main mIRC window
                    -3 = Currently active window (Default), -4 = Currently active dialog.

Examples:

dialog Example {
    Title "Testing"
    Size -1 -1 100 100
    Option dbu

    Tab "Tab 1", 100, 1 1 60 60
    Tab "Tab 2", 200
    Box "Test area", 23, 4 17 40 42
    Button "Finish", 1, 4 80 48 14, ok
    Edit "",2, 12 30 25 9 , Result, Tab 100
    Radio "Test 3",3, 12 30 30 12,Group, Tab 200
    Radio "Test 4",4, 12 45 30 12, Tab 200
    Item "&Test", 5, 810
    Item break,6, 810
    Item "&Hello",7,810
}
/dialog -m Test Example
var %test = $dialog(Test2,Example)  /* %test will get the text in the editbox */



Dialog events:

on <level>:DIALOG:<name>:<event>:<id>: {
    Parameters:
        <level> = User level that will trigger the event.
        <name> = Dialog name that triggers the event, can be a wildmatch.
        <event> = Dialog event type.
        <id> = Item ID that triggers the event.
    Arguments:
        $dname = The name of the dialog that triggered the event.
        $devent = The event type that was triggered.
        $did = The item ID that triggered the event. This $identifier has a lot of useful props: /help $did
        $dialog($dname) = The $identifier that contains the dialog's information.
        $didwm(name,id,wildtext,[N]) = In a list or combo, returns the number of the line that matches the wildtext.
                                                          The search starts in line N (optional).
        $didreg(name,id,regex,N) = In a list or combo, returns the number of the line that matches the regular expression.
                                                   The search starts in line N (optional).
        $didtok(name,id,c) = In a list, combo or editbox, returns a tokenized list of the text in the item.
    Events:
        init = just before a dialog is displayed, controls can be initialized in this event. id is zero.
        close = when a dialog is closed.
        edit = text in editbox or combo box changed.
        sclick = single click in list/combo box, or check/uncheck of radio/check buttons, or click of a button.
        dclick = double click in list/combo box.
        menu = a menu item was selected.
        scroll = scroll control position has changed.
    Events not associated with an ID:
        mouse = mouse moved
        sclick = left button down
        uclick = left button up
        dclick = double click
        rclick = right button click
        drop = drop click
}

Example:
/*I'm using the dialog table in the dialog prefix example */
on *:dialog:test*:init:*: {
did -c $dname 4
    dialog -t $dname Test Example
}
on *:dialog:test*:sclick:3: {
    did -ra $dname 2 $did(3)
}
on *:dialog:test*:sclick:4: {
    did -ra $dname 2 $did(4)
}